From 91d0693411cd1e078039a72c351603edad1605e9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 31 May 2023 14:49:11 -0500 Subject: [PATCH] Standardize on an RST section "underline" scheme --- doc/README | 5 +++++ doc/src/appendices.m4 | 6 +++--- doc/src/architecture/databases.m4 | 6 +++--- doc/src/architecture/schemas.m4 | 8 ++++---- doc/src/architecture/users.m4 | 2 +- doc/src/intro/about_db.m4 | 6 +++--- doc/src/intro/about_doc.m4 | 4 ++-- 7 files changed, 21 insertions(+), 16 deletions(-) create mode 100644 doc/README diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..c004e5d --- /dev/null +++ b/doc/README @@ -0,0 +1,5 @@ +The documentation is written in RST, processed with Sphinx and it's +extensions. There are a number of conventions: + +The section "underline" hierarchy is as given in the RST docs: +https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections \ No newline at end of file diff --git a/doc/src/appendices.m4 b/doc/src/appendices.m4 index 8878b52..1932671 100644 --- a/doc/src/appendices.m4 +++ b/doc/src/appendices.m4 @@ -35,7 +35,7 @@ These technologies are used by SokweDB. The desire is to keep the number of technologies to a minimum to keep development simple. Operating System Components and Services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +```````````````````````````````````````` * The Microsoft Azure cloud * The Linux Operating System Kernel @@ -57,7 +57,7 @@ specific PostgreSQL characteristics and features. Development Tools -^^^^^^^^^^^^^^^^^ +````````````````` * The SQL database query and construction language * The PL/pgSQL PostgreSQL database extension language @@ -71,7 +71,7 @@ Development Tools Documentation Tools -^^^^^^^^^^^^^^^^^^^ +``````````````````` * The `ReStructured Text`_ (RST) markup lanugage * The Sphinx_ RST processor diff --git a/doc/src/architecture/databases.m4 b/doc/src/architecture/databases.m4 index e925b47..62a5acf 100644 --- a/doc/src/architecture/databases.m4 +++ b/doc/src/architecture/databases.m4 @@ -28,13 +28,13 @@ SokweDB utilizes at least 3 databases, each for a different purpose. There may also be other databases available.\ [#f8]_ sokwedb -^^^^^^^ +``````` The ``sokwedb`` database contains the final, "official", data. All research takes place in this database. sokwedb_test -^^^^^^^^^^^^ +```````````` The ``sokwedb_test`` database is used, by everyone, for testing. Typically, this database contains a copy of the ``sokwedb`` data. It @@ -44,7 +44,7 @@ the data to be cleaned and examinations made before upload into production. sokwedb_copy -^^^^^^^^^^^^ +```````````` The ``sokwedb_copy`` database is a 2nd database for testing and development. It might be used by the system's developers to try new diff --git a/doc/src/architecture/schemas.m4 b/doc/src/architecture/schemas.m4 index 42430f6..eac1945 100644 --- a/doc/src/architecture/schemas.m4 +++ b/doc/src/architecture/schemas.m4 @@ -30,13 +30,13 @@ herein; it is likely that some schemas will be created to hold shared data, data not part of SokweDB itself but related to it. The sokwedb schema -^^^^^^^^^^^^^^^^^^ +`````````````````` The ``sokwedb`` schema contains the data collected in the field. It is the primary schema of interest to the researcher. The codes schema -^^^^^^^^^^^^^^^^ +```````````````` The ``codes`` schema contains those tables which control the data vocabulary defining the codes able to be recorded in the database. @@ -57,7 +57,7 @@ data collection process. The upload schema -^^^^^^^^^^^^^^^^^ +````````````````` The ``upload`` schema contains the views used during the data upload process. These are, usually, of interest only to those who upload @@ -65,7 +65,7 @@ data into the database. The per-user private schemas -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +```````````````````````````` Individuals are given their own schemas in which they can do whatever they wish. So each regular account/login/username has an associated diff --git a/doc/src/architecture/users.m4 b/doc/src/architecture/users.m4 index 25414d4..90243d1 100644 --- a/doc/src/architecture/users.m4 +++ b/doc/src/architecture/users.m4 @@ -49,7 +49,7 @@ with SQL, e.g.:: Or grants can be made through some other mechanism. Superusers -^^^^^^^^^^ +`````````` `Superusers`_ have permission to do anything with a database, create and destroy tables, create and destroy user logins, etc. Only a few diff --git a/doc/src/intro/about_db.m4 b/doc/src/intro/about_db.m4 index 20fd0b9..5ddc1f0 100644 --- a/doc/src/intro/about_db.m4 +++ b/doc/src/intro/about_db.m4 @@ -68,7 +68,7 @@ Individual accounts are given their own, private, workspaces which allows for better long-term data maintenance. About Databases -^^^^^^^^^^^^^^^ +``````````````` In PostgreSQL a database is a stand-alone data store. Queries can easily interact with and combine all data kept within a single @@ -95,7 +95,7 @@ the "birthdate"column. .. _views: About Views -^^^^^^^^^^^ +``````````` Views appear to be tables but they are not. Views are virtual, when queried they deliver the results of a query run against the database's @@ -127,7 +127,7 @@ data upload to do analysis. .. _about_schemas: About Schemas -^^^^^^^^^^^^^ +````````````` Schemas partition databases.\ [#f7]_ \ [#f2]_ They work like directories or folders do in filesystems, but can be only one level diff --git a/doc/src/intro/about_doc.m4 b/doc/src/intro/about_doc.m4 index 316cc7a..9c107f5 100644 --- a/doc/src/intro/about_doc.m4 +++ b/doc/src/intro/about_doc.m4 @@ -34,7 +34,7 @@ describe the details of how to operate all related programs, or maintain the underlying software. Conventions -^^^^^^^^^^^ +``````````` In other words, this document describes the system's capabilities. How to use the system on a day-to-day basis, which features are used @@ -71,7 +71,7 @@ the terminology in use at the JGI and may need some study for those not familiar with it. A Guide for the Reader -^^^^^^^^^^^^^^^^^^^^^^ +`````````````````````` This is a reference document, and as such is not expected to be read from front-to-back. -- 2.34.1